home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / c / debugc.zip / BUG.DOC < prev    next >
Text File  |  1985-07-18  |  3KB  |  96 lines
  1.  
  2.  
  3.     Bug.h     Copyright (c) 1985   Dr. Bob's Utilities
  4.     This file  may be used freely without royalty or fee.
  5.     No warranty of any kind is expressed or implied.
  6.  
  7.                    Dr. Bob's Utilities
  8.                    444 Maple Lane
  9.                    St. Paul,  MN  55112
  10.  
  11.     Dr. Bob can be reached at
  12.  
  13.                    Terrapin Station BBS
  14.                    (612) 623-0152
  15.                    HOURS - 24 hours a day, every day
  16.  
  17.  
  18.     Bug.h is a set of macro definitions that allow you fairly fine
  19.     control over what parts of a program execute.  It allows you to
  20.     designate portions of code and printf statements that will execute
  21.     only when you are debugging, and portions that will execute only
  22.     when you are NOT debugging.  Debugging messages can be left in the
  23.     source code at no cost in object size.  Time consuming portions of
  24.     code that are known to work well can be skipped during debugging and
  25.     will automatically be included in a regular compile.  Messages that
  26.     identify functions or specific locations as well as the value of
  27.     variables will automatically be included when debugging and ignored
  28.     when not debugging.
  29.  
  30.     The compiler directive -D is used to tell the compiler when you
  31.     are debugging; when debugging use:
  32.  
  33.                 cc  -ddebug  file.c
  34.  
  35.     When through debugging, use:
  36.  
  37.                 cc  file.c
  38.  
  39.     Put the following include as the last of your include statements:
  40.  
  41.     #include bug.h
  42.  
  43.     Then you can use the following macros to set up your file and the
  44.     compiler will handle the details.
  45.  
  46.  
  47.     The following two macros take the place of printf() statements
  48.     you would normally use for debugging.  All the normal printf()
  49.     functions are supported.
  50.     
  51.     DB_PRINT(stuff);  prints stuff only when Debug is defined
  52.     NDB_PRINT(stuff);  prints stuff only when Debug is NOT defined
  53.  
  54.     Inside of parends is exactly like inside of parends in printf()
  55.     EXCEPT!  you must use COMMA instead of actual ","  The word
  56.     COMMA must be in capital letters (So must DB_PRINT etc.)
  57.  
  58.     Example:   DB_PRINT("This will be printed only when debugging\n");
  59.                DB_PRINT("x = %d   temp = %s" COMMA x COMMA temp);
  60.  
  61.  
  62.     The following two macros allow sections of code to be ignored
  63.     or executed depending on whether you are debugging or not.
  64.  
  65.     DEBUG(
  66.           statement;
  67.           statement;
  68.           etc.
  69.           )       statements execute only when debug is defined
  70.  
  71.     N_DEBUG(
  72.           statement;
  73.           statement;
  74.           etc.
  75.           )     statements execute only when debug is NOT defined
  76.  
  77.     Your compiler may limit the amount of material allowed between
  78.     the parends of these statements.  You may get a "Macro too long"
  79.     error.  If so, split the stuff up into several DEBUG( sections.
  80.  
  81.  
  82.     The following macro provides an easy way to tell how far a program
  83.     gets in execution. the "msg" in HERE is usually a label or the
  84.     name of the current function.
  85.  
  86.     HERE("msg")  put anywhere in source file will print the
  87.     msg, source file name and line number on screen if debug is defined
  88.     ... otherwise HERE() is ignored & uses no memory.
  89.  
  90.  
  91.     see bug.c for examples of how to use these macros
  92.  
  93.     have fun,
  94.  
  95.                  Dr. Bob
  96.